﻿#region Using Statements
using System;
#endregion

namespace DirectZZT.Shared.Core
{
    /// <summary>
    /// Defines the mechanisms for a logging class that performs various logging tasks.
    /// </summary>
    public interface ILogging
    {
        /// <summary>
        /// Gets/sets the max file size in bytes of the log file before it gets cleaned up.
        /// </summary>
        int MaxFileSize { get; set; }

        /// <summary>
        /// Logs a normal, unformatted text.
        /// </summary>
        /// <param name="type">The message type.</param>
        /// <param name="source">The component from which this type comes (optional).</param>
        /// <param name="category">The category under which this log message is filed under (optional).</param>
        /// <param name="message">The message.</param>
        void Log(LoggingMessageType type, string source, string category, string message);
        /// <summary>
        /// Logs formatted text.
        /// </summary>
        /// <param name="type">The message type.</param>
        /// <param name="source">The component from which this type comes (optional).</param>
        /// <param name="category">The category under which this log message is filed under (optional).</param>
        /// <param name="format">The text to use as the format string.</param>
        /// <param name="arguments">The arguments to use for the format string.</param>
        void LogFormat(LoggingMessageType type, string source, string category, string format, params object[] arguments);
        /// <summary>
        /// Logs a <see cref="Exception"/>.
        /// </summary>
        /// <param name="source">The component from which this type comes (optional).</param>
        /// <param name="exception">The exception.</param>
        void LogException(string source, Exception exception);
        /// <summary>
        /// Adds an empty entry to the log file.
        /// </summary>
        void AddBlankLine();
        /// <summary>
        /// Adds a neutral separator to the log file.
        /// </summary>
        void AddSeparator();
        /// <summary>
        /// Removes the underlying log file and returns the result.
        /// </summary>
        /// <returns>The result of the deleting operation.</returns>
        bool DeleteLogFile();

        /// <summary>
        /// Sets the caching mode for this logging instance.
        /// </summary>
        /// <remarks>Setting <paramref name="cacheSize"/> to a higher value results in less writes to the hard disk, while app crashes may result in an incomplete log file.
        /// Setting <paramref name="cacheSize"/> to a lower value results in more writes to the hard disk but ensures that the log is complete.</remarks>
        /// <param name="cacheSize">The cache size to set. See documentation for further information.</param>
        /// <exception cref="System.ArgumentException"><paramref name="cacheSize"/> was set to an invalid value (below zero or above an implementation-specific limit).</exception>
        void SetCacheMode(int cacheSize);
        /// <summary>
        /// Sets the output file.
        /// Next time something is logged it goes into the file given here.
        /// </summary>
        /// <param name="fileName">The new output file.</param>
        /// <exception cref="System.ArgumentException">Parameter <paramref name="fileName"/> was a file that was not absolute.</exception>
        void SetOutputFileName(string fileName);
        /// <summary>
        /// Flushes the most recent logging history by writing all cached entries to the file and clearing the cache.
        /// </summary>
        void Flush();
        /// <summary>
        /// Returns an array containing all log entries of this logging instance,
        /// optionally starting at the given timestamp.
        /// </summary>
        /// <param name="start">The optional timestamp of the entries to take. Use <c>null</c> to return all entries (caution).</param>
        /// <returns>An array containing all log entries of this logging instance,
        /// optionally starting at the given timestamp.</returns>
        LogEntry[] GetEntries(Nullable<DateTime> start);

        /// <summary>
        /// Initializes this logging instance.
        /// </summary>
        void Initialize();
        /// <summary>
        /// Called when the host application is shutting down. Used to clean-up the caches (if any), finish writing to the hard disk, etc.
        /// </summary>
        void Shutdown();

        /// <summary>
        /// Registers a new <see cref="ILoggingListener"/>.
        /// </summary>
        /// <param name="listener">The <see cref="ILoggingListener"/> to register.</param>
        void RegisterListener(ILoggingListener listener);
        /// <summary>
        /// Unregisters an existing <see cref="ILoggingListener"/>.
        /// </summary>
        /// <param name="listener">The <see cref="ILoggingListener"/> to unregister.</param>
        void UnregisterListener(ILoggingListener listener);
    }
}
